home *** CD-ROM | disk | FTP | other *** search
/ Delphi 2.0 - Programmer's Utilities Power Pack / Delphi 2.0 Programmer's Utilities Power Pack.iso / s_to_z / tpw32_10 / usage.txt < prev    next >
Encoding:
Text File  |  1996-09-15  |  6.1 KB  |  150 lines
  1.  
  2. ORIGINAL DOCUMENTATION BY CHRISTIAN GHISLER
  3. -------------------------------------------
  4.  
  5.  CALL32nt.pas: Library for Delphi/TPW/BPW to call 32 bit functions
  6.                in Windows NT or Windows 95
  7.  
  8. Adapted to Pascal by Christian Ghisler
  9. from CALL32.DLL, a DLL for Visual Basic 
  10. written and placed in the Public Domain by Peter Golde
  11.  
  12. This unit is placed in the public domain.
  13. Please feel free to redistribute as you wish.  
  14. No guarantees are made as to its suitability or
  15. usefulness, and no support can be provided.
  16.  
  17.  
  18. To call a function in a 32-bit DLL, follow these steps:
  19.  
  20.  1. Declare the function you wish to call. Declare it
  21.  in the ordinary fashion, with the following exceptions:
  22.  
  23.  >  Declare it as a function variable
  24.  >  Add an additional argument at the end, of type Longint:
  25.  
  26.  For example, if you are calling the function:  (C code)
  27.  
  28.     GetWindowText(HWND hwnd, LPSTR lpsz, int cch)
  29.  
  30.  declare it as follows (remember that ints and all handles
  31.  are 32 bits, so use a Longint):
  32.  
  33.     var GetWindowText:function(hwnd:Longint;lpsz:PChar;cch:longint;id:Longint):Longint;
  34.  
  35.  2. Each function needs an identifier to distinguish the function from other called
  36.     functions. Declare this identifier in a var block.
  37.  
  38. For the above example:
  39.  
  40.     var id_GetWindowText:longint;
  41.  
  42.  3. In the initialization section of your application, set the 
  43.     address of the called function to the address of Call32:
  44.  
  45.     @GetWindowtext:=@Call32;
  46.  
  47.  4. Also in the initialization section of your application,
  48.  declare the actual library and name of the function you 
  49.  want to call with the Declare32 function. Pass it the name
  50.  of the function (CASE SENSITIVE!!!), the library name, and
  51.  a string describing the argument types. 
  52.  
  53.  Each letter in the string declares the type of one argument,
  54.  and should be either "i" for a 32-bit integer or handle
  55.  type, "p" for any pointer type, or "w" for an HWND parameter
  56.  to which you want to pass a 16-bit HWND and have it be
  57.  automatically converted to a 32-bit HWND. Save the return
  58.  value of Declare32 in a global variable to pass as the last
  59.  parameter to the function you declared earlier. So, in
  60.  continuing the example, you would call:
  61.  
  62.    id_GetWindowText:=Declare32('GetWindowText','user32','wpi');
  63.  
  64.  (As a side note, this more properly would be declared as
  65.  'GetWindowTextA', since this is the real exported name.
  66.  However, Declare32 will automatically add an 'A' to the
  67.  end of a function name if necessary.)
  68.  
  69.  To call the function, you would call:
  70.  
  71.    cbCopy:=GetWindowText(hwnd, sz, cb, id_GetWindowText);
  72.  
  73.  It is important to use the correct data types when calling
  74.  DLL functions. There are two important points to pay
  75.  attention to when using CALL32NT.PAS.
  76.  
  77.  First, only 32-bit integers can be passed to a DLL
  78.  procedure. Since virtually all 32-bit functions take int,
  79.  UINT, LONG, DWORD, or HANDLE parameters, which are all 32
  80.  bits, this is not a major restriction. However, you must
  81.  remember to always declare function arguments as Longint,
  82.  not Integer.
  83.  
  84.  Second, 16-bit handles and 32-bit handles are not
  85.  interchangeable. For example, a 16-bit bitmap handle that
  86.  you get from calling a 16-bit DLL or from the Delphi/TPW
  87.  environment cannot be passed to a 32-bit function
  88.  expecting a bitmap handle. Similarly, a 32-bit handle
  89.  obtained from a 32-bit function cannot be passed to a 16-
  90.  bit DLL. The only exception is window handles (HWND). If
  91.  you declare a function parameter with the "w" letter in
  92.  the argument description string passed to Declare32, the
  93.  corresponding parameter will be automatically converted
  94.  from a 16-bit HWND to a 32-bit HWND when the call is made.
  95.  You must still declare the argument as a LONG. This is
  96.  convenient, for example, when passing the value returned
  97.  by the "handle" property of a form/control to a 32-bit DLL
  98.  function. Only windows created by your application can be
  99.  translated.
  100.  
  101.  The following is a summary of data types:
  102.  
  103.  C data type    Type specified in Declare   Character for Declare32
  104.    int, UINT           Longint                   i
  105.    LONG, DWORD         Longint                   i
  106.    HANDLE              Longint                   i
  107.    WORD, short         not supported
  108.    HWND                Longint                   w (i for no 16->32 translation)
  109.    LPSTR               PChar                     p
  110.    LPLONG, LPDWORD,
  111.    LPUINT, int FAR *   VAR x:Longint             p
  112.    LPWORD              VAR x:Word                p
  113.  
  114.  Note on Declare32 function names: Declare32 will
  115.  automatically try three different names for the function
  116.  name you pass in. First, it uses the exact name you pass
  117.  in. If it doesn't find that function name, it converts the
  118.  name to the stdcall decorated name convention by adding an
  119.  underscore at the beginning and adding "@nn" at the end,
  120.  where "nn" is the number of bytes of arguments. If it
  121.  doesn't find that name, it adds an "A" to the end of the
  122.  original name to try the Win32(R) ANSI function calling
  123.  convention.
  124.  
  125.  If there occurs an error in Declare32, the returned id will
  126.  be less than 0. Also, the variable Call32NTError will be set,
  127.  so you only have to check one variable to check that all went
  128.  well. You can use this variable to distinguish between Windows
  129.  3.1 and Windows NT/95: if Call32NTError is false, you can use
  130.  the declared 32-bit functions, otherwise you must use 16-bit
  131.  replacement functions.
  132.  This allows you to write programs which work in both 16 and 32
  133.  bit environments.
  134.  
  135.  If you have to pass a record containing a pointer, you must use
  136.  the function GetVDMPointer32W to create a 0:32 pointer from
  137.  your 16:16 pointer.
  138.  
  139.  This unit is, like the original DLL, in the public domain.
  140.  Feel free to redistribute as you wish. No guarantees are 
  141.  made as to its suitability or usefulness, and no support
  142.  is provided. Please send bug reports to my CIS address
  143.  100332,1175.
  144.  
  145.  CALL32NT requires the Microsoft Windows NT operating system
  146.  or Windows 95 Preview or later to perform its task. The program
  147.  will also run in Win 3.1, but of course the functions will not
  148.  work.
  149.  
  150.